package org.marketlive.entity.attributes;

/*
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
*/

import java.util.List;

/**
 * Represents the home object for managing attribute types.
 */
public interface IAttributeTypeHome extends IEntityHome {

    /** Represents the checkbox attribute type. */
    public static final String ATTRIBUTE_TYPE_CHECKBOX = "Checkbox";
    /** Represents the currency attribute type. */
    public static final String ATTRIBUTE_TYPE_CURRENCY = "Currency";
    /** Represents the date attribute type. */
    public static final String ATTRIBUTE_TYPE_DATE = "Date";
    /** Represents the file attribute type. */
    public static final String ATTRIBUTE_TYPE_FILE = "File";
    /** Represents the image attribute type. */
    public static final String ATTRIBUTE_TYPE_IMAGE = "Image";
    /** Represents the list attribute type. */
    public static final String ATTRIBUTE_TYPE_LIST = "List";
    /** Represents the numeric attribute type. */
    public static final String ATTRIBUTE_TYPE_NUMERIC = "Numeric";
    /** Represents the text attribute type. */
    public static final String ATTRIBUTE_TYPE_TEXT = "Text";
    /** Represents the long text attribute type. */
    public static final String ATTRIBUTE_TYPE_TEXTLONG = "Text - Long";
    /** Represents the URL attribute type. */
    public static final String ATTRIBUTE_TYPE_URL = "URL";
    /** Represents the attribute types known to the system. */
    public static final String[] ATTRIBUTE_TYPES = {ATTRIBUTE_TYPE_CHECKBOX, ATTRIBUTE_TYPE_CURRENCY, ATTRIBUTE_TYPE_DATE, ATTRIBUTE_TYPE_FILE, ATTRIBUTE_TYPE_IMAGE, ATTRIBUTE_TYPE_LIST, ATTRIBUTE_TYPE_NUMERIC, ATTRIBUTE_TYPE_TEXT, ATTRIBUTE_TYPE_TEXTLONG, ATTRIBUTE_TYPE_URL};


    /** Represents the site attribute level. */
    public static final String ATTRIBUTE_LEVEL_SITE = "site";
    /** Represents the category attribute level. */
    public static final String ATTRIBUTE_LEVEL_CATEGORY = "category";
    /** Represents the pgroup attribute level. */
    public static final String ATTRIBUTE_LEVEL_PGROUP = "pgroup";
    /** Represents the product attribute level. */
    public static final String ATTRIBUTE_LEVEL_PRODUCT = "product";
    /** Represents the SKU attribute level. */
    public static final String ATTRIBUTE_LEVEL_SKU = "sku";
    /** Represents the content attribute level. */
    public static final String ATTRIBUTE_LEVEL_CONTENT = "content";
    /** Represents all the attribute levels known to the system. */
    public static final String[] ATTRIBUTE_LEVELS = {ATTRIBUTE_LEVEL_SITE, ATTRIBUTE_LEVEL_CATEGORY, ATTRIBUTE_LEVEL_PGROUP, ATTRIBUTE_LEVEL_PRODUCT, ATTRIBUTE_LEVEL_SKU, ATTRIBUTE_LEVEL_CONTENT};

    /** Root folder name for the category attribute type. */
    public static final String ATTRIBUTE_ROOT_FOLDER_CATEGORY = "Category/PGroup"; //"Product Category"
    /** Root folder name for the product group attribute type. */
    public static final String ATTRIBUTE_ROOT_FOLDER_PGROUP = "Category/PGroup"; //"Product Group";
    /** Root folder name for the product attribute type. */
    public static final String ATTRIBUTE_ROOT_FOLDER_PRODUCT = "Product";
    /** Root folder name for the sku attribute type. */
    public static final String ATTRIBUTE_ROOT_FOLDER_SKU = "SKU";
    /** Root folder name for category and product groups. (Not used.) */
    public static final String ATTRIBUTE_ROOT_FOLDER_CATEGORY_AND_PGROUP = "Category/Product Group";

    /**
     * Persists a new instance of <code>objectDO</code>. Returns the identifier of the persisted object.
     *
     * @param       objectDO an AttributeDO or AttributeTypeDO with all values populated except the ID for AttributeDO
     * @return      the identifier of the persisted object
     * @throws      Exception if an error occurs
     */
    public int insert(Object objectDO) throws Exception;

    /**
     * Returns <code>IAttributeType</code>s with the given <code>levelType</code>.
     *
     * @param levelType one of the {@link #ATTRIBUTE_LEVELS} known to the system
     * @return a collection of <code>IAttributeType</code>s
     * @throws      Exception if an error occurs
     */
    public List findByLevel(String levelType) throws Exception;

    /**
     * Returns <code>IAttributeType</code>s with the given <code>levelType</code> and <code>type</code>.
     *
     * @param       levelType one of the {@link #ATTRIBUTE_LEVELS} known to the system
     * @param       type one of the {@link #ATTRIBUTE_TYPES} known to the system
     * @return      a collection of <code>IAttributeType</code>s
     * @throws      Exception if an error occurs
     */
    public List findByLevelAndType(String levelType, String type) throws Exception;

    /**
     * Returns <code>IAttributeType</code>s in the given category.
     * Not implemented by the default implementation.
     *
     * @param       category a user-defined attribute category
     * @return      a collection of <code>IAttributeType</code>s
     * @throws      Exception if an error occurs
     */
    public List findByCategory(String category) throws Exception;

    /**
     * Returns a collection of <code>IAttribute</code>s or <code>AttributeType</code>s, depending on the implementation,
     * that match both arg1 and arg2 criteria inputs.
     *
     * @param       category a user-defined attribute category
     * @param       levelType one of the {@link #ATTRIBUTE_LEVELS} known to the system
     * @return      a collection of <code>IAttributeType</code>s
     * @throws      Exception if an error occurs
     */
    public List findByCategoryAndLevel(String category, String levelType) throws Exception;

    /**
     * Updates a collection of <code>IAttributeTypeDO</code>s based on the given attribute list.
     *
     * @param       attributeList a collection of <code>IAttributeTypeDO</code>s with all values populated
     * @return      the number of records updated, or 0 if the operation failed
     * @throws      Exception if an error occurs
     */
    public int updateAll(List attributeList) throws Exception;

    /**
     * Returns a collection of <code>AttributeUsageDO</code>s that describe where the attribute with the given
     * identifier is used.
     * @param attributeID identifier of the <code>IAttribute</code> for which to find the usage
     * @param levelType which level this attribute applies to. One of the {@link #ATTRIBUTE_LEVELS} known to the system.
     * @return the <code>AttributeUsageDO</code>s that describe where the attribute is used
     * @throws Exception if an error occurs
     */
    public List findAttributeUseage(Integer attributeID, String levelType) throws Exception;

    /**
     * Returns all attribute categories.
     * Not implemented in the default implementation.
     *
     * @return a collection of strings representing all existing attribute categories
     * @throws Exception if an error occurs
     */
    public List findAttributeCategories() throws Exception;

    /**
     * Returns all attribute categories for the given level type.
     * <code>levelType</code> must be one of the {@link #ATTRIBUTE_LEVELS} known to the system.
     *
     * @return a collection of strings representing all attribute categories for the given level type
     * @throws Exception if an error occurs
     */
    public List findAttributeCategories(String levelType) throws Exception ;

    /**
     * Returns the <code>IAttributeCategory</code> with the given identifier.
     *
     * @param catID the ID of the category for which to find details
     * @return the <code>IAttributeCategory</code> with the given identifier
     * @throws Exception if an error occurs
    */
    public IAttributeCategory findCategoryDetails(Integer catID) throws Exception ;

    /**
     * Updates the given attribute category.
     *
     * @param category the <code>IAttributeCategory</code> to update
     * @return the number of records updated, or 0 if the operation fails
     * @throws Exception if an error occurs
     */
    public int updateCategoryDetails(IAttributeCategory category) throws Exception ;

    /**
     * Creates a new attribute category with the given name, level, and description.
     *
     * @param name the name of the category to insert
     * @param levelType one of the {@link #ATTRIBUTE_LEVELS} known to the system
     * @param description a description of the category. May be null or empty.
     * @return the return code from the SQL transaction
     * @throws Exception if an error occurs
     */
    public int insertCategory(String name, String levelType, String description) throws Exception;

    /**
     * Associates the <code>IAttribute</code> having the given <code>attID</code>
     * to the <code>IAttributeCategory</code> having the given <code>catID</code>.
     *
     * @param attID the identifier of the attribute to link
     * @param catID the identifier of the category to link
     * @return the return code from the SQL transaction
     * @throws Exception if an error occurs
     */
    public int linkAttributeToCategory(Integer attID, Integer catID) throws Exception;

    /**
     * Removes an attribute-to-category link.
     *
     * @param attID the identifier of the attribute to unlink from categories
     * @return the return code from the SQL transaction
     * @throws Exception if an error occurs
     */
    public int unLinkAttributeFromCategory(Integer attID) throws Exception;


    /**
     * Returns a new <code>IAttributeType</code>.
     *
     * @return a new instance of an <code>IAttributeType</code>
     */
    public IAttributeType getAttributeType();

    /**
     * Returns a new <code>IAttributeCategory</code>.
     * @return a new instance of an <code>IAttributeCategory</code>
     */
    public IAttributeCategory getAttributeCategory();


    /**
     * Returns a new <code>IAttributeTypeLIDO</code>.
     * @return a new instance of an <code>IAttributeTypeLIDO</code>
     */
    public IAttributeTypeLIDO getAttributeTypeLido();

    /**
     * Returns a collection of <code>IAttributeType</code>s that are not in use.
     *
     * @param       levelID one of the {@link #ATTRIBUTE_LEVELS} known to the system
     * @param       levelType one of the {@link #ATTRIBUTE_TYPES} known to the system
     * @return      a collection of <code>IAttributeType</code>s
     * @throws      Exception if an error occurs
     */
    List findByLevelUnassigned(Integer levelID, String levelType) throws Exception;

    /**
     * Returns a collection of <code>IAttributeType</code>s that are not in use in a category.
     *
     * @param       levelType one of the {@link #ATTRIBUTE_TYPES} known to the system
     * @return      a collection of <code>IAttributeType</code>s
     * @throws      Exception if an error occurs
     */
    List findByLevelUnassignedToCategory(String levelType) throws Exception;

}
